Celestin Apprentice 7

home *** CD-ROM | disk | FTP | other *** search

/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / PowerPlant / CURLPushButton 2.3 / CURLPushButton README < prev next >

Wrap

Text File | 1997-07-21 | 19.6 KB | 426 lines | [TEXT/CWIE]

/*******************************************************************************\ | | | CURLPushButton ©1997 John C. Daub. All rights reserved | | | | John C. Daub <mailto:hsoi@eden.com> | | <http://www.eden.com/~hsoi/> <http://www.eden.com/~hsoi/prog.html> | | | \*******************************************************************************/ DESCRIPTION ``````````` A Metrowerks PowerPlant® inherited class geared towards helping your application become Internet-savvy. It allows you to put clickable buttons in places (e.g. your About box) that will look like a URL in a web browser...click on the URL and go right to there! Great for listing the web page for your software, the email address for contact/support, the ftp site where users can get updates or whatever you want! You list the text, they can see it, copy it down, whatever... and then just click and visit it. VERY HANDY!! VERY COOL!! The class is even set up that the text of the button can say one thing but then still visit the URL. For example, the About Box displays your name and you click on it and it visits your personal web page or something. Point is, the button can list the URL text or not...it's a flexible class. There is a demonstration application included in the archive to help you see how it works as well as help and tips for implimentation. Furthermore there is a CPPb/CTYP file that you can use to aid in the editing process (for use with Metrowerks Constructor). IMPORTANT: CURLTextButton gets a lot of its functionality from the wonderful Internet Configuration System, courtesy of Peter N. Lewis and Quinn! the Eskimo. It is not necessary to use Internet Config with CURLTextButton, but it might simplify things for you if you do use it. If nothing else, the demo application uses Internet Config. This means that you can use CURLTextButton alone, but then you'll have to impliment your own schemes for finding and launching the correct application, sending the URL to it, etc etc. So, why reinvent the wheel? Use IC :) If you wish to use IC to help impliment this, you will need the Internet Config Programmers Kit. This is available for free online in many sources. I'll list the URL to obtain this and other information a little further down in this file. Also, you might find IC++ from Dan Crevier very helpful here too. IC++ are some C++ wrappers that make implimenting IC in your application a lot easier. I used IC++ in the demo application, and I'll give you a URL for the full package again later in this document. MINIMAL PORTIONS OF THE INTERNET CONFIG PROGRAMMERS KIT AND IC++ SHIP IN THIS ARCHIVE, BUT ONLY SO THE DEMO CAN COMPILE. IF YOU WISH TO USE IC AND/OR IC++ YOU SHOULD OBTAIN THE FULL ARCHIVES FOR THESE AS THEY WILL CONTAIN ALL THE NECESSARY FILES, DOCUMENTATION, SUPPORT/CONTACT INFORMATION ABOUT/FOR THE AUTHOR(S), ETC. Again, URL's are below. I'll provide more information about using CURLPushButton in a bit :) Upgraded to work with CodeWarrior Professional 1, CURLPushButton tries to take advantage of the latest PowerPlant developments, e.g. using CTYP resources, using the RegisterClass_() macro instead of a static CreateFromStream method. However, I've done what I can to try to have some degree of backwards compatability within the source. The demo was built using CW Pro1. WHAT'S NEW WITH 2.0 ``````````````````` In version 1.0 (the previous version of the class), it was ok...it behaved like a push button variation of LTextButton. It worked and did the job, but cosmetically I didn't really like it. The HotSpotAction just called InvertRect, which was ok to give visual feedback, but wasn't as clean as say how a link/URL in a web browser would be. I really wanted the class to behave in a similar way, InvertRect didn't cut it. So I modified the class to just invert the actual text. This was accomplished by drawing the string not in srcOr mode but in srcXor mode. That worked ok to give me the behavior that I wanted. However, the exact inverse color that one could get could be less than aestheticly pleasing...like blue inverted to yellow...didn't look that nice. So I decided to allow the ability to specify the RGB color to use when the button was hilited. This worked out ok because you could want to have a blue color when "untouched" and then something like red for when it was hilited...again similar to the "default" behavior of web browsers. But then I thought that people might want to have more than just a different color when the button was depressed, like change the style. So here's how it now works: Create a Txtr resource for the "normal" look and feel...usually at least you'll want srcOr copy mode and centered. Font, size, style, color are up to you. Now if you want to use a custom Text Trait for the "depressed" state, make another along the same lines as the other Txtr, but I'm sure you'll at least want a different color. Specify the "depressed" Txtr ID in the "Hilited Text Traits" field (in Constructor). If there is an ID in that field greater than -1 (0 or higher), then the Txtr will be used. If the value in that field is a negative number, then we fall to the next chioce...using the specified hilite color. If the "Use Hilite Color" box is checked, then the RGB Value specified will be used for the hilite color. If it's not checked, then we fall upon the last resort, using the "main" Txtr and just using a srcXor copy mode. I have tried to demonstrate how this "roll-down-hill" approach works in the demo application. Check it out and look at the PPob in Constructor. That should help. Also what's new in 2.0 are new constructors, a copy and parameterized constructor. Most importantly, the parameterized constructor, due to the many parameters that go into it, has a struct that you'll need to fill out. It's similar to SPaneInfo or SViewInfo in concept and purpose. And since I no longer inherit from LTextButton, hopefully things can be a bit better in terms of implimentation. Finally, I went from v1.0 straight to 2.0 because well....it was such a major overhaul. :) DUE TO THIS MAJOR OVERHAUL, I HONESTLY DOUBT THAT THERE IS ENOUGH BACKWARDS COMPATABILITY WITH VERSION 1.0. IF YOU ARE CURRENTLY USING v1.0, PLEASE USE THE 1.0 CTYP/CPPb TO REMOVE YOUR CURLPushButton's FROM YOUR PPob's. THEN RECONSTRUCT THEM WITH THE NEW VERSION. I apologize if this causes any problems, but hopefully with a little time to convert things over, you'll be able to enjoy and appreciate the new functionality of the overhauled class. HOW TO USE CURLPushButton ````````````````````````` First of course are the "usual" PowerPlant things.... There are 2 files: "CURLPushButton 2.0.CTYP" contains the CTYP resource for Constructor v2.4 and greater, and "CURLPushButton 2.0.CPPb" containing the CPPb resource for Constructor versions less than 2.4. You can place these files (or copies of, or aliases to) into the "Custom Types" folder in your "Metrowerks PowerPlant" folder (if you are working with something prior to CW Pro1, you can place the file in the same folder as the Constructor application). This way Constructor, upon launch, will list CURLPushButton in the Catalog Window (or Display Classes for Constructor < v2.4), and it will be available to like any other PowerPlant class (LPane, LButton, etc.) Then you can just drag the CURLPushButton icon from that window into your PPob resource and go! Nice ease of editing, just like what Constructor allows for :-) When you're editing in Constructor, you might want to make a custom Text Traits resource ('Txtr') for the button. Since the point of the class is to show a URL and be similar in look and feel to URLs in web browsers, I found it nice to create a Txtr that was blue and underlined (and my choice of Geneva 9 was arbitrary). I also found it handy to have the text be aligned to the center, since it will look better when clicked upon. You can see in the demo's .ppob file how I did this. Coloring isn't a feature inherent to the CURLPushButton class, hence why you need to do it this way. It's not vital to have a custom Txtr for the CURLPushButton, but it makes the button/URL look like that of a web browser and so can lend some nonverbal cues to the user that if they "click here" something just might happen. :) Oh, when you make your Text Trait, I'd recommend using a "srcOr" copy mode, especially if you have a non-white background (like a grayscale dialog, as in the demo). This will allow the background to show through. Play around...you'll see what I mean. Then in your code you should make sure the CURLPushButton class is registered (RegisterClass_() macro or URegistrar::RegisterClass()), and the CURLPushButton.cp file is added to your project file. As then for getting everything to work, it's just a matter of the PowerPlant broadcaster/listener mechanism. If you're not familiar with this mechanism, I highly suggest that you read the chapter on Controls (which discusses this) in the "PowerPlant Book" by Jim Trudeau. This book is in the "CodeWarrior Documentation" folder on the CodeWarrior Reference CD. You can see in the sample code what I do. Most important thing is to have some place/object to ListenToMessage. In the demo, I had the CURLTestDialog object ListenToMessage. When the button's value message is broadcast, I do check a few things...let me back up a bit... Notice in the CURLTestDialog constructor I make a CInternetConfig object? This is from Dan Crevier's IC++. If you don't want to use IC++, you should initialize and start up your IC stuff here (if not done already elsewhere). If you get IC started up and working right (i.e. it's installed on the user's system, no problems getting it initialized, etc etc etc) then you're good to go. I set a Boolean (mICWorking) based upon the success/failure of IC starting up. You might want to do this same thing yourself because you see...if you GetURL(), that's ok...but then if you try to send the URL, you're in trouble...IC's not installed or a problem starting it up, and who knows how your app might fail. If you don't use IC, then hopefully you'll come up with your own mechanisms to check for this sort of thing. Bottom line of this is that before we GetURL and then send it off to launch the appropriate helper application, we of course check for the proper MessageT and then also check to be sure we can do the URL (e.g. mICWorking == true). This is a very necessary thing to do. With the demo's implimentation, the CURLPushButton will still click, but then nothing will happen. One nice thing is that the Internet Config system is in the public domain. You are welcome to ship the IC application/extension with your application (or if you want to keep file size small, give a URL). This can help users utilize all features of your application, get them using Internet Config (cause if you're on the net and have a Mac, there's little reason to not use IC), and life can be good :) I think that about covers how to use CURLPushButton. Hopefully between this and the demo application you should be able to get things going. If not, of course contact me and I'll help you out. And if these docs are insufficient, please let me know how to improve upon them. Oh I should say...the implimentation that I use in CURLTestDialog of course does work...but it's hardly the best ghing...there should be better error checking, there are a lot of assumptions made, and that's not good code -- it's just something to suffice for a simple demo. Base your own code upon it if you wish, but do try to handle errors better, contend with odd situations better, etc. CREDITS ``````` I wrote this because well...I wanted to have something that would do this :) I should thank Dan Crevier for IC++, Peter N. Lewis and Quinn! for Internet Config, Ron Davis (friend and co-worker) and James Thomson (author of the VERY COOL DragThing) for a bit of inspiration, Matt Brunk for the drag and drop code and suggestion (and the cool SpeedSearch!), and my wife Michele for putting up with me as I spend all day long at work on a computer and then come home and spend all night on a computer. :) DISCLAIMER `````````` This is NOT a product of Metrowerks Corporation. Please do NOT contact Metrowerks for help/support of this class/code. If you need support, please use the contact information given below. LICENSING AND USAGE AGREEMENT ````````````````````````````` John C. Daub (author) grants you, and you accept, a nonexclusive, nontransferable license to distribute this code for you within your programs and projects. You may distribute this code in object code form only and only on magnetic diskettes, CD-ROM, or other media with your programs into which this code has been incorporated (if you need to distribute your program by some other medium, please contact the author). You agree that this license gives you no title nor rights of ownership in, of, and/or to this code, and acknowledge that this code is property of John C. Daub. This code is NOT in the public domain. Permission is granted to the following organizations to distribute this code on their CD-ROM collections: Pacific HiTech, Inc - Info-Mac CD-ROM Celestin Company - Apprentice CD Meterowerks Corporation - CodeWarrior Bowers Development - AppMaker If you and/or your organization wishes to distribute this code and are not explicitly listed above, please contact John C. Daub. You may modify the source code, compile it, and incorporate the resulting object code into your programs. If you modify the code, you cannot redistribute the modified code under the same class/code name. Furthermore, to prevent any problems and/or infringements, please contact the author prior to redistribution of any modified code. John C. Daub licenses this code to you on an "AS IS" basis. John C. Daub makes no warranties, neither expressed nor implied, regarding this code, its merchantability, nor its fitness for any purpose. John C. Daub agrees to make a reasonable effort to provide written or verbal corrections for any problems that might be found in this code. Use of this code must be credited in an appropriate manner and location (such as printed or online documentation and/or About boxes) with the following credit line: CURLPushButton ©1997 John C. Daub. All rights reserved. If this license is too restrictive with the current law in your state or country, you should not use this code at all. Furthermore, if you personally find this agreement too restrictive or not to your satisfaction, you should not use this code at all. FUTURE `````` - Overall, I'm much happier with v2.0 than v1.0. Looks better, behaves better, no LTextButton baggage. But the one bummer is that because I inherit from LControl, editing the PPob in Constructor isn't that WYSIWYG...you can't display the title, which is a bummer. I work around it by creating an LCaption into which I put the same title as the CURLPushButton...and then I can size up the LCaption and make the CURLPushButton's rect match up. It helps to get around...but... Maybe depending where Constructor goes in terms of custom resources, I might not need to do anything...I like the overall structure where it is, and if Constructor will eventually have ways to make the editing better, then I'll wait. - Add more functionality, if needed. The 2.0 version just had the functionality that I personally needed, so if there are other things that you might want to see, please let me know. I'm very open to suggestions and all feedback (good or bad). CONTACT INFORMATION ``````````````````` Even though you don't need to send me email or register or anything to use the code, it would still be nice to drop me a line and let me know what you think. If you find any bugs or add any cool features, send them to me so I can add it to the official distribution. Furthermore, if I have your contact information, I can notify you when new versions are released -- can be very handy if say there is a fatal crashing bug in the code or some such. So, it's probably in your own best interest to drop me a line :-) Also, be sure to visit my web site <http://www.eden.com/~hsoi/prog.html> and "register". I won't know if you're "registered" or not, but it's a nice way that you can be notified of product updates (e.g. I make a new version, post it on that page, if you're registered, you'll be emailed automatically that the page changed). John C. Daub <mailto:hsoi@eden.com> <http://www.eden.com/~hsoi/prog.html> Internet Config URLs: <http://www.stairways.com/> <http://www.stairways.com/ic/index.html> <ftp://ftp.stairways.com//stairways/source/icprogkit1.3.sit.bin> IC++ from Dan Crevier <http://rhino.harvard.edu/dan/Programming.html> <ftp://rhino.harvard.edu//pub/dan/IC++1.0b2.hqx> CHANGE HISTORY `````````````` Date Vers Who Notes ---------------------------------------------------------------------------- 29 Jan 97 1.0 JCD - Created and initial release 01 Feb 97 2.0 JCD - Total rewrite of the class: inherits now from LControl instead of LTextButton (now has copy and parameterized ctors as well as no more of LTextButton's baggage and limits); hilite of the button no longer InvertRect's (still optionally can) but instead can use a second Txtr to specify the hilite, else uses the one Txtr but then a custom hilite color, else just TextMode(srcXOr) to auto-invert; CTYP/CPPb updated to match new capabilites. 19 Feb 97 2.1 JCD - added preprocessor directives for DebugNew - added functionality so that when the pane is not active the text is drawn dimmed. Required modifications to DrawSelf, as well as adding ActivateSelf and DeactivateSelf. 22 Jun 97 2.2 JCD - Updated the licensing agreement. - Cleaned up the sources for readability - Can now compile without any precompiled headers. - Upgraded to CW Pro1 - Expanded SURLpbInfo typedef. - Created assignment operator. - Made DrawSelf protected, as it should be. 21 July 97 2.3 JCD - All ctor's use initialization lists instead of assignment (where possible). - All member data is now private (was protected). Appropriate accessor functions have been created (as public or protected, depending on context). Helps to further abstract the user away from the data (good C++ style). - Added include for PowerPlant_PCH to be consistant with PowerPlant sources. - Inline functions no longer defined within class declaration. Definitions moved outside of the class, but still in the header file. #pragma mark's added to source file to ease navigation and user indexing. - GetInvertRect and SetInvertRect made inline (to be consistant with the above changes). GetInvertRect made const and Set takes a const parameter now. These names made obsolete (tho kept for backwards compatability. All new code should use GetUseInvertRect and SetUseInvertRect instead. - Updated demo so clicking on the OK button in the dialog just quits the application. - Added code to support drag and drop of the control/url so people could more easily get the text for other purposes. Code courtesy of Matt Brunk. (thanx!). This code is optional on two levels: 1. compiler via the _CURLPushButton_DO_DND_ preprocessor directive (for those that desire no drag and drop support at all) 2. via DoDragAndDrop(), a runtime method to let you set if a URL button supports this or not (so you can be selective). I didn't want to change the PPob format, so I opted for this technique. Updated demo to suit. - Updated licensing agreement to include Bowers Development and AppMaker, as CURLPushButton will be part of that package.